Title: RECIO DESIGN AND DEVELOPMENT NOTES Copyright: (C) 1994 William Pierpoint Version: 2.02 Date: May 5, 1994 1.0 DATA STRUCTURES 1.1 REC structure for each record stream * defined in recio.h. * one static REC for recin (included in ROPEN_MAX count). * allocate dynamic array of RECs dimensioned to ROPEN_MAX-NREC in ropen(). * Each REC has two associated buffers: 1) record string buffer containing current record; allocate when first record read; reallocate if record becomes larger. 2) field string buffer containing current field; allocate when first field read; reallocate if field becomes larger. * deallocate dynamic RECs and associated buffers in rclose() and rcloseall() if all record streams closed; deallocate associated buffers for recin with an exit function registered with atexit(). 1.2 REC r_flags assignments Bit Description ----- ------------------------------------------------------------- 0 If clear, colno start at 0; if set, colno start at 1 1 if clear, read mode; if set, write/append mode 2-6 Reserved 7 If clear, EOF not reached; if set, EOF reached 8-11 If clear, no error; else, rerror number 12-15 if clear, no warning; else, rwarning number 1.3 Accessing REC Members and Associated Buffers How do I * access the name of the record stream? rnames() * access the current context number? rcxtno() * access the current record number? rrecno() * access the current field number? rfldno() * access the current column number? rcolno() * access the record string buffer? rrecs() * access the field string buffer? rflds() * determine if column numbers start at 0 or 1 rbegcolno() * determine if there are more records left? reof() * determine if there is an error on the stream? rerror() * determine if there is a warning on the stream? rwarning() * access the error message for the stream? rerrstr() * force an error on a record stream? rseterr() * clear an error on a record stream? rclearerr() * increase the size of the record string buffer? rsetrecsiz() * increase the size of the field string buffer? rsetfldsiz() * replace the data in the field string buffer? rsetfldstr() * set the field delimiter character? rsetfldch() * set the text delimiter character? rsettxtch() * set the context number? rsetcxtno() * set column numbering to start at 0 or 1? rsetbegcolno() 2.0 CODE STRUCTURES 2.1 Structure Chart ΙΝΝΝΝΝΝΝΝΝ» Ί recio.c Ί ΘΝΡΝΝΡΝΝΡΝΌ ³ ³ ³ ΙΝΝΝΝΝΝΝΝ» input ³ ³ ³ output ΙΝΝΝΝΝΝΝΝ» Ί rget.c ΗΔΔΔΔΔΔΔΔΔΔΔΩ ³ ΐΔΔΔΔΔΔΔΔΔΔΆ rput.c Ί char ΘΝΡΝΝΝΝΡΝΌ column ³ char ΘΝΡΝΝΝΝΡΝΌ column delimited ³ ³ delimited ³ delimited ³ ³ delimited ΙΝΝΝΝΝΝΝΝΝ» ³ ³ ΙΝΝΝΝΝΝΝΝΝΝ» ³ ΙΝΝΝΝΝΝΝΝΝ» ³ ³ ΙΝΝΝΝΝΝΝΝΝΝ» Ί rgets.c ΗΔ΄ ΓΔΆ rcgets.c Ί ³ Ί rputs.c ΗΔ΄ ΓΔΆ rcputs.c Ί ΘΝΝΝΝΝΝΝΝΝΌ ³ ³ ΘΝΝΝΝΝΝΝΝΝΝΌ ³ ΘΝΝΝΝΝΝΝΝΝΌ ³ ³ ΘΝΝΝΝΝΝΝΝΝΝΌ ³ ³ ³ ³ ³ ΙΝΝΝΝΝΝΝΝΝ» ³ ³ ΙΝΝΝΝΝΝΝΝΝΝ» ³ ΙΝΝΝΝΝΝΝΝΝ» ³ ³ ΙΝΝΝΝΝΝΝΝΝΝ» Ί rgetf.c ΗΔ΄ ΓΔΆ rcgetf.c Ί ³ Ί rputf.c ΗΔ΄ ΓΔΆ rcputf.c Ί ΘΝΝΝΝΝΝΝΝΝΌ ³ ³ ΘΝΝΝΝΝΝΝΝΝΝΌ ³ ΘΝΝΝΝΝΝΝΝΝΌ ³ ³ ΘΝΝΝΝΝΝΝΝΝΝΌ ³ ³ ³ ³ ³ ΙΝΝΝΝΝΝΝΝΝ» ³ ³ ΙΝΝΝΝΝΝΝΝΝΝ» ³ ΙΝΝΝΝΝΝΝΝΝ» ³ ³ ΙΝΝΝΝΝΝΝΝΝΝ» Ί rbget.c ΗΔΩ ΐΔΆ rcbget.c Ί ³ Ί rbput.c ΗΔΩ ΐΔΆ rcbput.c Ί ΘΝΝΝΝΝΝΝΝΝΌ ΘΝΝΝΝΝΝΝΝΝΝΌ ³ ΘΝΝΝΝΝΝΝΝΝΌ ΘΝΝΝΝΝΝΝΝΝΝΌ ³ ΙΝΝΝΝΝΝΝΝΝΝ» ³ ΙΝΝΝΝΝΝΝΝΝ» ΙΝΝΝΝΝΝΝΝΝΝ» Ί rwarn.c ΗΔΔΔΑΔΔΔΆ rerr.c ΗΔΔΔΔΔΔΔΔΆ rfix.c Ί ΘΝΝΝΝΝΝΝΝΝΝΌ ΘΝΝΝΝΝΝΝΝΝΌ ΘΝΝΝΝΝΝΝΝΝΝΌ 2.2 Callback Error Function Skeleton if valid record pointer [risvalid(rp)] if past end of file [reof(rp)] (if reof test removed, past EOF will else [error number set] become R_EMISDAT or R_WEMPSTR) switch error number [rerror(rp)] case read data errors [R_ERANGE || R_EINVDAT || R_EMISDAT] case write data errors [R_ENOPUT] switch context number [rcxtno(rp)] case RECIN switch field number [rfldno(rp)] case 1 (first field read) case 2 (second field read) ... endcase ... default [missing or unknown context number] endcase case out of memory [R_ENOMEM] case fatal errors [R_EINVAL || R_EINVMOD] default [possibly set by application with rseterr()] endcase endif else [invalid record pointer] switch error number [errno] case out of memory [ENOMEM] case out of record or file pointers [EMFILE] case permission denied [EACCES] case fatal errors [EINVAL] default [possibly set by application with rseterr()] endcase endif 2.3 Callback Warning Function Skeleton if valid record pointer [risvalid(rp)] switch warning number [rwarning(rp)] case read data warnings [R_WEMPSTR] case write data warnings [R_WWIDTH] case code runtime warnings [R_WNOREG] default [possibly set by application with rsetwarn()] endcase endif 3.0 DEVELOPMENT NOTES 3.1 fgets (Microsoft C 5.1) Previous notes of mine indicate that Microsoft's fgets function does not work correctly when it reads a line of text that consists of only a newline. However this can be worked around by first setting the string buffer to an empty string. If you plan on retaining the newline, you will need to test this further. The fgets function is used twice in the rgetrec function. If porting to Microsoft C, you may need to implement this fix in rget.c: *rrecs(rp) = '\0'; /* just prior to the first fgets (added v1.20) */ *str = '\0'; /* just prior to the second fgets */ 3.2 fopen (Borland C 3.1) fopen() calls __openfp() calls open(). Borland's "Library Reference" documents error numbers for open(), but not for fopen(). These error numbers are ENOENT, EMFILE, EACCES, and EINVACC. Because ropen() screens the access code, the EINVACC error should not occur from the recio library. 3.3 strtol & strtoul (Borland C 3.1) These functions stop consuming input once they overflow, setting ERANGE. Hence endptr can point into the middle of a sequence of valid characters having the expected form as given in ANSI X3.159-1989, Sections 4.10.1.5 and 4.10.1.6. IMHO this characteristic is not in conformance with the ANSI standard as endptr should only point to the first unrecognized character or to the terminating null character. Borland's strtod does not have this problem. Note that ANSI X3.159-1989 Section 4.10.1.6 allows strtoul (unsigned long) to have an optional negative sign. A negative unsigned long? Borland 3.1 strtoul converts a negative long to an unsigned number without error. But I prefer to trap any negative numbers input to unsigned fields. So str2ul is a wrapper function for strtoul that first tests for a negative number and if one is found, flags the data as invalid and returns zero. The test suite includes -0 as a data value. The strtol function traps this as an ERANGE error and returns the overflow limit. The rfixi and rfixl functions substitute zero. 3.4 strtod (Borland C 3.1) Unlike the strtol and strtoul functions, strtod does not clear errno first. Starting with recio version 2.02, errno is cleared before any conversions where recio code checks the value of errno after the conversion. It is also cleared when a record stream is successfully opened.